%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                               %
%                       Legal Notice                            %
%                                                               %
% This document is copyright (C) Olaf Kirch, okir@monad.swb.de  %
%                                                               %
% For copying conditions, please refer to the file COPYING.	%
%                                                               %
% The author is not liable for any damages, direct or indirect, %
% resulting from the use of information provided in this        %
% document.                                                     %
%                                                               %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% When viewing this document with vi on an 80-columns screen,   %
% do a ':se nonumber' first.                                    %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                               %
%               S T A R T   O F   C H A P T E R                 %
%                                                               %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\chapter{Setting up the Serial Hardware}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{serial}
\index{hardware!serial|(}
\index{device, serial|(}

There are rumors that there are some people out there in netland who
only own one PC and don't have the money to spend on a T1~Internet link.
To get their daily dose of news and mail nevertheless, they are said to
rely on SLIP links, UUCP networks, and bulletin board systems (BBS's)
that utilize public telephone networks.


\index{Hankins, Greg}
\index{HOWTO!Serial}
This chapter is intended to help all those people who rely on modems to
maintain their link. However, there are many details that this chapter
cannot go into, for instance how to configure your modem for dialin. All
these topics will be covered in the upcoming Serial HOWTO by Greg
Hankins,\footnote{
 To be reached at \email{gregh@cc.gatech.edu}.
} to be posted to \ngrp{comp.os.linux.announce} on a regular basis.



\section{Communication Software for Modem Links}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{serial.software}
\index{terminal programs}
\index{BBS}
\index{bulletin board}

There are a number of communication packages available for \linux. Many
of them are \emph{terminal programs} which allow a user to dial into
another computer as if she was sitting in front of a simple terminal.
The traditional terminal program for \unices{} is \prog{kermit}. It is,
however, somewhat Spartan. There are more comfortable programs
available that support a dictionary of telephone numers, script languages
for calling and logging into remote computer systems, etc. One of them
is \prog{minicom}, which is close to some terminal programs former
DOS users might be accustomed to. There are also X-based communications
packages, e.g. \prog{seyon}.


Also, a number of \linux-based BBS packages are available for people
that want to run a bulletin board system.  Some of these packages can be
found at \host{sunsite.unc.edu} in \file{/pub/Linux/system/Network}.


\index{UUCP}
\index{FidoNet}
Apart from terminal programs, there is also software that uses a serial
link non-interactively to transport data to or from your computer. The
advantage of this technique is that it takes much less time to download
a few dozen kilobytes automatically, than it might take you to read your
mail on-line in some mailbox and browse a bulletin board for interesting
articles. On the other hand, this requires more disk storage because of
the loads of useless information you usually get.


The epitome of this sort of communications software is UUCP. It is a
program suite that copies files from one host to another, executes
programs on a remote host, etc. It is frequently used to transport mail
or news in private networks. Ian Taylor's UUCP package, which also runs
under \linux{}, is described in the following chapter.  Other
non-interactive communication software is, for example, used throughout
Fidonet. Ports of Fidonet applications like \prog{ifmail} are also
available.


\index{SLIP}
SLIP, the serial line Internet protocol, is somewhat inbetween,
allowing both interactive and non-interactive use. Many people
use SLIP to dial up their campus network or some other sort of
public SLIP server to run FTP sessions, etc. SLIP may however also
be used over permanent or semi-permanent connections for LAN-to-LAN
coupling, although this is really only interesting with ISDN.



\section{Introduction to Serial Devices}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{serial.ttys}
\index{tty|(}

The devices a \unix{} kernel provides for accessing serial devices are
typically called \emph{ttys}. This is an abbreviation for \emph{Teletype}\TM,
which used to be one of the major manufacturers of terminals in the
early days of Unix.  The term is used nowadays for any character-based data
terminal.  Throughout this chapter, we will use the term exclusively to
refer to kernel devices.


\linux{} distinguishes three classes of ttys: (virtual) consoles,
pseudo-terminals (similar to a two-way pipe, used by application such as
X11), and serial devices.  The latter are also counted as ttys, because
they permit interactive sessions over a serial connection; be it from a
hard-wired terminal or a remote computer over a telephone line.


Ttys have a number of configurable parameters which can be set using the
\func{ioctl(2)} system call. Many of them apply only to serial devices,
since they need a great deal more flexibility to handle varying types of
connections.


\index{line discipline}
\index{tty!line discipline}
Among the most prominent line parameters are the line speed and parity.
But there are also flags for the conversion between upper and lower case
characters, of carriage return into line feed, etc. The tty driver may
also support various \emph{line disciplines} which make the device
driver behave completely different. For example, the SLIP driver for
\linux{} is implemented by means of a special line discipline.


\index{serial line!speed}
\index{modem, speed}
\index{Baud rate}
\index{Bit rate}
There is a bit of ambiguity about how to measure a line's speed.  The
correct the term is \emph{Bit rate}, which is related to the line's transfer
speed measured in bits per second (or bps for short).  Sometimes, you hear
people refer to it as the \emph{Baud rate}, which is not quite correct.
These two terms are, however, not interchangeable. The Baud rate
refers to a physical characteristic of some serial device, namely the
clock rate at which pulses are transmitted.  The bit rate rather
denotes a current state of an existing serial connection between two
points, namely the average number of bits transferred per second. It
is important to know that these two values are usually different, as
most devices encode more than one bit per electrical pulse.



\section{Accessing Serial Devices}
\label{serial.devices}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Like all devices in a \unix{} system, serial ports are accessed
through device special files, located in the \file{/dev} directory.
There are two varieties of device files related to serial drivers,
and for each port, there is one device file from each of them.
Depending on the file it is accessed by, the device will behave
differently.


\index{dev/cua*@\file{/dev/cua*}|(}
\index{dev/ttyS*@\file{/dev/ttyS*}|(}
\index{serial line!device file}
\index{dialout device}
\index{dialin device}
The first variety is used whenever the port is used for dialing in; it
has a major number of~4, and the files are named \file{ttyS0},
\file{ttyS1}, etc. The second variety is used when dialing out
through a port; the files are called \file{cua0}, etc, and
have a major number of~5.


\index{COM port}
\index{port!COM}
Minor numbers are identical for both types. If you have your modem on
one of the ports \file{COM1} through \file{COM4}, its minor number will
be the \file{COM} port number plus 63. If your setup is different from
that, for example when using a board supporting multiple serial lines,
please refer to the Serial Howto.


Assume your modem is on \file{COM2}. Thus its minor number will be~65,
and its major number will be 5 for dialing out.  There should be a
device \file{cua1} which has these numbers. List the serial ttys in
the \file{/dev} directory.  Columns 5 and 6 should show major and minor
numbers, respectively:


\begin{tscreen}
\begin{verbatim}
$ ls -l /dev/cua*
crw-rw-rw-   1 root     root       5,  64 Nov 30 19:31 /dev/cua0
crw-rw-rw-   1 root     root       5,  65 Nov 30 22:08 /dev/cua1
crw-rw-rw-   1 root     root       5,  66 Oct 28 11:56 /dev/cua2
crw-rw-rw-   1 root     root       5,  67 Mar 19  1992 /dev/cua3
\end{verbatim}
\end{tscreen}


If there is no such device, you will have to create one: become
super-user and type


\begin{tscreen}
\begin{verbatim}
# mknod -m 666 /dev/cua1 c 5 65
# chown root.root /dev/cua1
\end{verbatim}
\end{tscreen}


\index{dev/modem@\file{/dev/modem}}
Some people suggest making \file{/dev/modem} a symbolic link to your
modem device, so that casual users don't have to remember the somewhat
unintuitive \file{cua1}. However, you cannot use \file{modem} in one
program, and the real device file name in another. This is because
these programs use so-called \emph{lock files} to signal that the
device is used. By convention, the lock file name for \file{cua1}, for
instance, is \file{LCK..cua1}.  Using different device files for the
same port means that programs will fail to recognize each other's lock
files, and will both use the device at the same time. As a result, both
applications will not work at all.


\index{dev/cua*@\file{/dev/cua*}|)}
\index{dev/ttyS*@\file{/dev/ttyS*}|)}


\section{Serial Hardware}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Intro to serial hardware, lightly touching RS 232 :-)
% Mebbe I should mention null modem cables?
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{serial.hardware}
\index{RS-232}

\linux{} currently supports a wide variety of serial boards which use
the RS-232 standard.  RS-232 is currently the most common standard for
serial communcications in the PC world. It uses a number of circuits for
transmitting single bits as well as for synchronization. Additional
lines may be used for signaling the presence of a carrier (used by
modems), and handshake.


\index{serial line!hardware handshake}
\index{handshake, hardware}
\index{hardware!handshake}
\index{RTS/CTS}
Although hardware handshake is optional, it is very useful. It allows
either of the two stations to signal whether it is ready to receive more
data, or if the other station should pause until the receiver is done
processing the incoming data.  The lines used for this are called
``Clear to Send'' (CTS) and ``Ready to Send'' (RTS), respectively, which
accounts for the colloquial name of hardware handshake, namely
``RTS/CTS''.


\index{16450 UART}
\index{16550 UART}
\index{UART}
In PCs, the RS-232 interface is usually driven by a UART chip derived
from the National Semiconductor~16450 chip, or a newer version thereof,
the NSC~16550A\footnote{
 There was also a NSC~16550, but it's FIFO never really worked.
}. Some brands (most notably internal modems equipped with the Rockwell
chipset) also use completely different chips that have been programmed
to behave as if they were 16550's.


\index{8250 UART}
The main difference between 16450's and 16550's that the latter have a
FIFO buffer of 16 Bytes, while the former only have a 1-Byte buffer.
This makes 16450's suitable for speeds up to 9600~Baud, while higher
speeds require a 16550-compatible chip.  Besides these chips, \linux{}
also supports the 8250 chip, which was the original UART for the PC-AT.


In the default configuration, the kernel checks the four standard
serial ports \file{COM1} through \file{COM4}. These will be
assigned device minor numbers 64 through 67, as described above.


\index{configuring!serial port|(}
\index{setserial@\prog{setserial}}
\index{T'so, Theodore}
If you want to configure your serial ports properly, you should install
Ted Tso's \prog{setserial} command along with the \file{rc.serial}
script.  This script should be invoked from \file{/etc/rc} at system
boot time. It uses \prog{setserial} to configure the kernel serial
devices. A typical \file{rc.serial} script looks like this:


\begin{tscreen}
\begin{verbatim}
# /etc/rc.serial - serial line configuration script.
#
# Do wild interrupt detection
/sbin/setserial -W /dev/cua*

# Configure serial devices
/sbin/setserial /dev/cua0 auto_irq skip_test autoconfig
/sbin/setserial /dev/cua1 auto_irq skip_test autoconfig
/sbin/setserial /dev/cua2 auto_irq skip_test autoconfig
/sbin/setserial /dev/cua3 auto_irq skip_test autoconfig

# Display serial device configuration
/sbin/setserial -bg /dev/cua*
\end{verbatim}
\end{tscreen}


\noindent
Please refer to the documentation that comes along with \prog{setserial}
for an explanation of the parameters.

If your serial card is not detected, or the \prog{setserial -bg} command
shows an incorrect setting, you will have to force the configuration
by explicitly supplying the correct values. Users with internal modems equipped
with the Rockwell chipset are reported to experience this problem. If,
for example, the UART chip is reported to be a NSC~16450, while in fact
it is NSC~16550-compatible, you have to change the configuration command
for the offending port to


\begin{tscreen}
/sbin/setserial /dev/cua1 auto\_irq skip\_test autoconfig uart 16550
\end{tscreen}


Similar options exist to force \file{COM} port, base address, and IRQ
setting. Please refer to the \prog{setserial(8)} manual page.


\index{serial line!hardware handshake}
\index{handshake, hardware}
\index{hardware!handshake}
If your modem supports hardware handshake, you should make sure to
enable it. Surprising as it is, most communication programs do not
attempt to enable this by default; you have to set it manually instead.
This is best performed in the \file{rc.serial} script, using the
\prog{stty} command:


\begin{tscreen}
\$ stty crtscts < /dev/cua1
\end{tscreen}

To check if hardware handshake is in effect, use

\begin{tscreen}
\$ stty -a < /dev/cua1
\end{tscreen}

This gives you the status of all flags for that device; a flag
shown with a preceding minus as in \option{-crtscts} means that the
flag has been turned off.

\index{configuring!serial port|)}


\index{tty|)}
\index{device, serial|)}
\index{hardware!serial|)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                               %
%                E N D   O F   C H A P T E R                    %
%                                                               %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
